Autogenerated HTML docs for v1.7.7-419-g87009
diff --git a/gitweb.html b/gitweb.html new file mode 100644 index 0000000..6ecbbfd --- /dev/null +++ b/gitweb.html
@@ -0,0 +1,1442 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" + "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> +<meta name="generator" content="AsciiDoc 8.5.2" /> +<title>gitweb(1)</title> +<style type="text/css"> +/* Debug borders */ +p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 { +/* + border: 1px solid red; +*/ +} + +body { + margin: 1em 5% 1em 5%; +} + +a { + color: blue; + text-decoration: underline; +} +a:visited { + color: fuchsia; +} + +em { + font-style: italic; + color: navy; +} + +strong { + font-weight: bold; + color: #083194; +} + +tt { + color: navy; +} + +h1, h2, h3, h4, h5, h6 { + color: #527bbd; + font-family: sans-serif; + margin-top: 1.2em; + margin-bottom: 0.5em; + line-height: 1.3; +} + +h1, h2, h3 { + border-bottom: 2px solid silver; +} +h2 { + padding-top: 0.5em; +} +h3 { + float: left; +} +h3 + * { + clear: left; +} + +div.sectionbody { + font-family: serif; + margin-left: 0; +} + +hr { + border: 1px solid silver; +} + +p { + margin-top: 0.5em; + margin-bottom: 0.5em; +} + +ul, ol, li > p { + margin-top: 0; +} + +pre { + padding: 0; + margin: 0; +} + +span#author { + color: #527bbd; + font-family: sans-serif; + font-weight: bold; + font-size: 1.1em; +} +span#email { +} +span#revnumber, span#revdate, span#revremark { + font-family: sans-serif; +} + +div#footer { + font-family: sans-serif; + font-size: small; + border-top: 2px solid silver; + padding-top: 0.5em; + margin-top: 4.0em; +} +div#footer-text { + float: left; + padding-bottom: 0.5em; +} +div#footer-badges { + float: right; + padding-bottom: 0.5em; +} + +div#preamble { + margin-top: 1.5em; + margin-bottom: 1.5em; +} +div.tableblock, div.imageblock, div.exampleblock, div.verseblock, +div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock, +div.admonitionblock { + margin-top: 1.0em; + margin-bottom: 1.5em; +} +div.admonitionblock { + margin-top: 2.0em; + margin-bottom: 2.0em; + margin-right: 10%; + color: #606060; +} + +div.content { /* Block element content. */ + padding: 0; +} + +/* Block element titles. */ +div.title, caption.title { + color: #527bbd; + font-family: sans-serif; + font-weight: bold; + text-align: left; + margin-top: 1.0em; + margin-bottom: 0.5em; +} +div.title + * { + margin-top: 0; +} + +td div.title:first-child { + margin-top: 0.0em; +} +div.content div.title:first-child { + margin-top: 0.0em; +} +div.content + div.title { + margin-top: 0.0em; +} + +div.sidebarblock > div.content { + background: #ffffee; + border: 1px solid silver; + padding: 0.5em; +} + +div.listingblock > div.content { + border: 1px solid silver; + background: #f4f4f4; + padding: 0.5em; +} + +div.quoteblock, div.verseblock { + padding-left: 1.0em; + margin-left: 1.0em; + margin-right: 10%; + border-left: 5px solid #dddddd; + color: #777777; +} + +div.quoteblock > div.attribution { + padding-top: 0.5em; + text-align: right; +} + +div.verseblock > div.content { + white-space: pre; +} +div.verseblock > div.attribution { + padding-top: 0.75em; + text-align: left; +} +/* DEPRECATED: Pre version 8.2.7 verse style literal block. */ +div.verseblock + div.attribution { + text-align: left; +} + +div.admonitionblock .icon { + vertical-align: top; + font-size: 1.1em; + font-weight: bold; + text-decoration: underline; + color: #527bbd; + padding-right: 0.5em; +} +div.admonitionblock td.content { + padding-left: 0.5em; + border-left: 3px solid #dddddd; +} + +div.exampleblock > div.content { + border-left: 3px solid #dddddd; + padding-left: 0.5em; +} + +div.imageblock div.content { padding-left: 0; } +span.image img { border-style: none; } +a.image:visited { color: white; } + +dl { + margin-top: 0.8em; + margin-bottom: 0.8em; +} +dt { + margin-top: 0.5em; + margin-bottom: 0; + font-style: normal; + color: navy; +} +dd > *:first-child { + margin-top: 0.1em; +} + +ul, ol { + list-style-position: outside; +} +ol.arabic { + list-style-type: decimal; +} +ol.loweralpha { + list-style-type: lower-alpha; +} +ol.upperalpha { + list-style-type: upper-alpha; +} +ol.lowerroman { + list-style-type: lower-roman; +} +ol.upperroman { + list-style-type: upper-roman; +} + +div.compact ul, div.compact ol, +div.compact p, div.compact p, +div.compact div, div.compact div { + margin-top: 0.1em; + margin-bottom: 0.1em; +} + +div.tableblock > table { + border: 3px solid #527bbd; +} +thead, p.table.header { + font-family: sans-serif; + font-weight: bold; +} +tfoot { + font-weight: bold; +} +td > div.verse { + white-space: pre; +} +p.table { + margin-top: 0; +} +/* Because the table frame attribute is overriden by CSS in most browsers. */ +div.tableblock > table[frame="void"] { + border-style: none; +} +div.tableblock > table[frame="hsides"] { + border-left-style: none; + border-right-style: none; +} +div.tableblock > table[frame="vsides"] { + border-top-style: none; + border-bottom-style: none; +} + + +div.hdlist { + margin-top: 0.8em; + margin-bottom: 0.8em; +} +div.hdlist tr { + padding-bottom: 15px; +} +dt.hdlist1.strong, td.hdlist1.strong { + font-weight: bold; +} +td.hdlist1 { + vertical-align: top; + font-style: normal; + padding-right: 0.8em; + color: navy; +} +td.hdlist2 { + vertical-align: top; +} +div.hdlist.compact tr { + margin: 0; + padding-bottom: 0; +} + +.comment { + background: yellow; +} + +.footnote, .footnoteref { + font-size: 0.8em; +} + +span.footnote, span.footnoteref { + vertical-align: super; +} + +#footnotes { + margin: 20px 0 20px 0; + padding: 7px 0 0 0; +} + +#footnotes div.footnote { + margin: 0 0 5px 0; +} + +#footnotes hr { + border: none; + border-top: 1px solid silver; + height: 1px; + text-align: left; + margin-left: 0; + width: 20%; + min-width: 100px; +} + + +@media print { + div#footer-badges { display: none; } +} + +div#toc { + margin-bottom: 2.5em; +} + +div#toctitle { + color: #527bbd; + font-family: sans-serif; + font-size: 1.1em; + font-weight: bold; + margin-top: 1.0em; + margin-bottom: 0.1em; +} + +div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 { + margin-top: 0; + margin-bottom: 0; +} +div.toclevel2 { + margin-left: 2em; + font-size: 0.9em; +} +div.toclevel3 { + margin-left: 4em; + font-size: 0.9em; +} +div.toclevel4 { + margin-left: 6em; + font-size: 0.9em; +} +/* Overrides for manpage documents */ +h1 { + padding-top: 0.5em; + padding-bottom: 0.5em; + border-top: 2px solid silver; + border-bottom: 2px solid silver; +} +h2 { + border-style: none; +} +div.sectionbody { + margin-left: 5%; +} + +@media print { + div#toc { display: none; } +} + +/* Workarounds for IE6's broken and incomplete CSS2. */ + +div.sidebar-content { + background: #ffffee; + border: 1px solid silver; + padding: 0.5em; +} +div.sidebar-title, div.image-title { + color: #527bbd; + font-family: sans-serif; + font-weight: bold; + margin-top: 0.0em; + margin-bottom: 0.5em; +} + +div.listingblock div.content { + border: 1px solid silver; + background: #f4f4f4; + padding: 0.5em; +} + +div.quoteblock-attribution { + padding-top: 0.5em; + text-align: right; +} + +div.verseblock-content { + white-space: pre; +} +div.verseblock-attribution { + padding-top: 0.75em; + text-align: left; +} + +div.exampleblock-content { + border-left: 3px solid #dddddd; + padding-left: 0.5em; +} + +/* IE6 sets dynamically generated links as visited. */ +div#toc a:visited { color: blue; } +</style> +<script type="text/javascript"> +/*<+'])'); + // Function that scans the DOM tree for header elements (the DOM2 + // nodeIterator API would be a better technique but not supported by all + // browsers). + var iterate = function (el) { + for (var i = el.firstChild; i != null; i = i.nextSibling) { + if (i.nodeType == 1 /* Node.ELEMENT_NODE */) { + var mo = re.exec(i.tagName); + if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") { + result[result.length] = new TocEntry(i, getText(i), mo[1]-1); + } + iterate(i); + } + } + } + iterate(el); + return result; + } + + var toc = document.getElementById("toc"); + var entries = tocEntries(document.getElementById("content"), toclevels); + for (var i = 0; i < entries.length; ++i) { + var entry = entries[i]; + if (entry.element.id == "") + entry.element.id = "_toc_" + i; + var a = document.createElement("a"); + a.href = "#" + entry.element.id; + a.appendChild(document.createTextNode(entry.text)); + var div = document.createElement("div"); + div.appendChild(a); + div.className = "toclevel" + entry.toclevel; + toc.appendChild(div); + } + if (entries.length == 0) + toc.parentNode.removeChild(toc); +}, + + +///////////////////////////////////////////////////////////////////// +// Footnotes generator +///////////////////////////////////////////////////////////////////// + +/* Based on footnote generation code from: + * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html + */ + +footnotes: function () { + var cont = document.getElementById("content"); + var noteholder = document.getElementById("footnotes"); + var spans = cont.getElementsByTagName("span"); + var refs = {}; + var n = 0; + for (i=0; i<spans.length; i++) { + if (spans[i].className == "footnote") { + n++; + // Use [\s\S] in place of . so multi-line matches work. + // Because JavaScript has no s (dotall) regex flag. + note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1]; + noteholder.innerHTML += + "<div class='footnote' id='_footnote_" + n + "'>" + + "<a href='#_footnoteref_" + n + "' title='Return to text'>" + + n + "</a>. " + note + "</div>"; + spans[i].innerHTML = + "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n + + "' title='View footnote' class='footnote'>" + n + "</a>]"; + var id =spans[i].getAttribute("id"); + if (id != null) refs["#"+id] = n; + } + } + if (n == 0) + noteholder.parentNode.removeChild(noteholder); + else { + // Process footnoterefs. + for (i=0; i<spans.length; i++) { + if (spans[i].className == "footnoteref") { + var href = spans[i].getElementsByTagName("a")[0].getAttribute("href"); + href = href.match(/#.*/)[0]; // Because IE return full URL. + n = refs[href]; + spans[i].innerHTML = + "[<a href='#_footnote_" + n + + "' title='View footnote' class='footnote'>" + n + "</a>]"; + } + } + } +} + +} +/*]]>*/ +</script> +</head> +<body> +<div id="header"> +<h1> +gitweb(1) Manual Page +</h1> +<h2>NAME</h2> +<div class="sectionbody"> +<p>gitweb - + Git web interface (web frontend to Git repositories) +</p> +</div> +</div> +<div id="content"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To get started with gitweb, run <a href="git-instaweb.html">git-instaweb(1)</a> from a git repository. +This would configure and start your web server, and run web browser pointing to +gitweb.</p></div> +</div> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gitweb provides a web interface to git repositories. It’s features include:</p></div> +<div class="ulist"><ul> +<li> +<p> +Viewing multiple Git repositories with common root. +</p> +</li> +<li> +<p> +Browsing every revision of the repository. +</p> +</li> +<li> +<p> +Viewing the contents of files in the repository at any revision. +</p> +</li> +<li> +<p> +Viewing the revision log of branches, history of files and directories, + see what was changed when, by who. +</p> +</li> +<li> +<p> +Viewing the blame/annotation details of any file (if enabled). +</p> +</li> +<li> +<p> +Generating RSS and Atom feeds of commits, for any branch. + The feeds are auto-discoverable in modern web browsers. +</p> +</li> +<li> +<p> +Viewing everything that was changed in a revision, and step through + revisions one at a time, viewing the history of the repository. +</p> +</li> +<li> +<p> +Finding commits which commit messages matches given search term. +</p> +</li> +</ul></div> +<div class="paragraph"><p>See <a href="http://git.kernel.org/?p=git/git.git;a=tree;f=gitweb">http://git.kernel.org/?p=git/git.git;a=tree;f=gitweb</a> or +<a href="http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/">http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/</a> for gitweb source code, +browsed using gitweb itself.</p></div> +</div> +<h2 id="_configuration">CONFIGURATION</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Various aspects of gitweb’s behavior can be controlled through the configuration +file <em>gitweb_config.perl</em> or <em>/etc/gitweb.conf</em>. See the <a href="gitweb.conf.html">gitweb.conf(5)</a> +for details.</p></div> +<h3 id="_repositories">Repositories</h3><div style="clear:left"></div> +<div class="paragraph"><p>Gitweb can show information from one or more Git repositories. These +repositories have to be all on local filesystem, and have to share common +repository root, i.e. be all under a single parent repository (but see also +"Advanced web server setup" section, "Webserver configuration with multiple +projects' root" subsection).</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>our $projectroot = '/path/to/parent/directory';</tt></pre> +</div></div> +<div class="paragraph"><p>The default value for <tt>$projectroot</tt> is <em>/pub/git</em>. You can change it during +building gitweb via <tt>GITWEB_PROJECTROOT</tt> build configuration variable.</p></div> +<div class="paragraph"><p>By default all git repositories under <tt>$projectroot</tt> are visible and available +to gitweb. The list of projects is generated by default by scanning the +<tt>$projectroot</tt> directory for git repositories (for object databases to be +more exact; gitweb is not interested in a working area, and is best suited +to showing "bare" repositories).</p></div> +<div class="paragraph"><p>The name of repository in gitweb is path to it’s <tt>$GIT_DIR</tt> (it’s object +database) relative to <tt>$projectroot</tt>. Therefore the repository $repo can be +found at "$projectroot/$repo".</p></div> +<h3 id="_projects_list_file_format">Projects list file format</h3><div style="clear:left"></div> +<div class="paragraph"><p>Instead of having gitweb find repositories by scanning filesystem +starting from $projectroot, you can provide a pre-generated list of +visible projects by setting <tt>$projects_list</tt> to point to a plain text +file with a list of projects (with some additional info).</p></div> +<div class="paragraph"><p>This file uses the following format:</p></div> +<div class="ulist"><ul> +<li> +<p> +One record (for project / repository) per line; does not support line +continuation (newline escaping). +</p> +</li> +<li> +<p> +Leading and trailing whitespace are ignored. +</p> +</li> +<li> +<p> +Whitespace separated fields; any run of whitespace can be used as field +separator (rules for Perl’s "<tt>split(" ", $line)</tt>"). +</p> +</li> +<li> +<p> +Fields use modified URI encoding, defined in RFC 3986, section 2.1 +(Percent-Encoding), or rather "Query string encoding" (see +<a href="http://en.wikipedia.org/wiki/Query_string#URL_encoding">http://en.wikipedia.org/wiki/Query_string#URL_encoding</a>), the difference +being that SP (" ") can be encoded as "+" (and therefore "+" has to be +also percent-encoded). +</p> +<div class="paragraph"><p>Reserved characters are: "%" (used for encoding), "+" (can be used to +encode SPACE), all whitespace characters as defined in Perl, including SP, +TAB and LF, (used to separate fields in a record).</p></div> +</li> +<li> +<p> +Currently recognized fields are: +</p> +<div class="dlist"><dl> +<dt class="hdlist1"> +<repository path> +</dt> +<dd> +<p> + path to repository GIT_DIR, relative to <tt>$projectroot</tt> +</p> +</dd> +<dt class="hdlist1"> +<repository owner> +</dt> +<dd> +<p> + displayed as repository owner, preferably full name, or email, + or both +</p> +</dd> +</dl></div> +</li> +</ul></div> +<div class="paragraph"><p>You can generate the projects list index file using the project_index action +(the <em>TXT</em> link on projects list page) directly from gitweb; see also +"Generating projects list using gitweb" section below.</p></div> +<div class="paragraph"><p>Example contents:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>foo.git Joe+R+Hacker+<joe@example.com> +foo/bar.git O+W+Ner+<owner@example.org></tt></pre> +</div></div> +<div class="paragraph"><p>By default this file controls only which projects are <strong>visible</strong> on projects +list page (note that entries that do not point to correctly recognized git +repositories won’t be displayed by gitweb). Even if a project is not +visible on projects list page, you can view it nevertheless by hand-crafting +a gitweb URL. By setting <tt>$strict_export</tt> configuration variable (see +<a href="gitweb.conf.html">gitweb.conf(5)</a>) to true value you can allow viewing only of +repositories also shown on the overview page (i.e. only projects explicitly +listed in projects list file will be accessible).</p></div> +<h3 id="_generating_projects_list_using_gitweb">Generating projects list using gitweb</h3><div style="clear:left"></div> +<div class="paragraph"><p>We assume that GITWEB_CONFIG has its default Makefile value, namely +<em>gitweb_config.perl</em>. Put the following in <em>gitweb_make_index.perl</em> file:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>read_config_file("gitweb_config.perl"); +$projects_list = $projectroot;</tt></pre> +</div></div> +<div class="paragraph"><p>Then create the following script to get list of project in the format +suitable for GITWEB_LIST build configuration variable (or +<tt>$projects_list</tt> variable in gitweb config):</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>#!/bin/sh + +export GITWEB_CONFIG="gitweb_make_index.perl" +export GATEWAY_INTERFACE="CGI/1.1" +export HTTP_ACCEPT="*/*" +export REQUEST_METHOD="GET" +export QUERY_STRING="a=project_index" + +perl -- /var/www/cgi-bin/gitweb.cgi</tt></pre> +</div></div> +<div class="paragraph"><p>Run this script and save its output to a file. This file could then be used +as projects list file, which means that you can set <tt>$projects_list</tt> to its +filename.</p></div> +<h3 id="_controlling_access_to_git_repositories">Controlling access to git repositories</h3><div style="clear:left"></div> +<div class="paragraph"><p>By default all git repositories under <tt>$projectroot</tt> are visible and +available to gitweb. You can however configure how gitweb controls access +to repositories.</p></div> +<div class="ulist"><ul> +<li> +<p> +As described in "Projects list file format" section, you can control which +projects are <strong>visible</strong> by selectively including repositories in projects +list file, and setting <tt>$projects_list</tt> gitweb configuration variable to +point to it. With <tt>$strict_export</tt> set, projects list file can be used to +control which repositories are <strong>available</strong> as well. +</p> +</li> +<li> +<p> +You can configure gitweb to only list and allow viewing of the explicitly +exported repositories, via <tt>$export_ok</tt> variable in gitweb config file; see +<a href="gitweb.conf.html">gitweb.conf(5)</a> manpage. If it evaluates to true, gitweb shows +repositories only if this file named by <tt>$export_ok</tt> exists in its object +database (if directory has the magic file named <tt>$export_ok</tt>). +</p> +<div class="paragraph"><p>For example <a href="git-daemon.html">git-daemon(1)</a> by default (unless <tt>--export-all</tt> option +is used) allows pulling only for those repositories that have +<em>git-daemon-export-ok</em> file. Adding</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>our $export_ok = "git-daemon-export-ok";</tt></pre> +</div></div> +<div class="paragraph"><p>makes gitweb show and allow access only to those repositories that can be +fetched from via <tt>git://</tt> protocol.</p></div> +</li> +<li> +<p> +Finally, it is possible to specify an arbitrary perl subroutine that will +be called for each repository to determine if it can be exported. The +subroutine receives an absolute path to the project (repository) as its only +parameter (i.e. "$projectroot/$project"). +</p> +<div class="paragraph"><p>For example, if you use mod_perl to run the script, and have dumb +HTTP protocol authentication configured for your repositories, you +can use the following hook to allow access only if the user is +authorized to read the files:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>$export_auth_hook = sub { + use Apache2::SubRequest (); + use Apache2::Const -compile => qw(HTTP_OK); + my $path = "$_[0]/HEAD"; + my $r = Apache2::RequestUtil->request; + my $sub = $r->lookup_file($path); + return $sub->filename eq $path + && $sub->status == Apache2::Const::HTTP_OK; +};</tt></pre> +</div></div> +</li> +</ul></div> +<h3 id="_per_repository_gitweb_configuration">Per-repository gitweb configuration</h3><div style="clear:left"></div> +<div class="paragraph"><p>You can configure individual repositories shown in gitweb by creating file +in the <em>GIT_DIR</em> of git repository, or by setting some repo configuration +variable (in <em>GIT_DIR/config</em>, see <a href="git-config.html">git-config(1)</a>).</p></div> +<div class="paragraph"><p>You can use the following files in repository:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +README.html +</dt> +<dd> +<p> + A html file (HTML fragment) which is included on the gitweb project + "summary" page inside <tt><div></tt> block element. You can use it for longer + description of a project, to provide links (for example to project’s + homepage), etc. This is recognized only if XSS prevention is off + (<tt>$prevent_xss</tt> is false, see <a href="gitweb.conf.html">gitweb.conf(5)</a>); a way to include + a README safely when XSS prevention is on may be worked out in the + future. +</p> +</dd> +<dt class="hdlist1"> +description (or <tt>gitweb.description</tt>) +</dt> +<dd> +<p> + Short (shortened to <tt>$projects_list_description_width</tt> in the projects + list page, which is 25 characters by default; see + <a href="gitweb.conf.html">gitweb.conf(5)</a>) single line description of a project (of a + repository). Plain text file; HTML will be escaped. By default set to +</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>Unnamed repository; edit this file to name it for gitweb.</tt></pre> +</div></div> +<div class="paragraph"><p>from the template during repository creation, usually installed in +<em>/usr/share/git-core/templates/</em>. You can use the <tt>gitweb.description</tt> repo +configuration variable, but the file takes precedence.</p></div> +</dd> +<dt class="hdlist1"> +category (or <tt>gitweb.category</tt>) +</dt> +<dd> +<p> + Singe line category of a project, used to group projects if + <tt>$projects_list_group_categories</tt> is enabled. By default (file and + configuration variable absent), uncategorized projects are put in the + <tt>$project_list_default_category</tt> category. You can use the + <tt>gitweb.category</tt> repo configuration variable, but the file takes + precedence. +</p> +<div class="paragraph"><p>The configuration variables <tt>$projects_list_group_categories</tt> and +<tt>$project_list_default_category</tt> are described in <a href="gitweb.conf.html">gitweb.conf(5)</a></p></div> +</dd> +<dt class="hdlist1"> +cloneurl (or multiple-valued <tt>gitweb.url</tt>) +</dt> +<dd> +<p> + File with repository URL (used for clone and fetch), one per line. + Displayed in the project summary page. You can use multiple-valued + <tt>gitweb.url</tt> repository configuration variable for that, but the file + takes precedence. +</p> +<div class="paragraph"><p>This is per-repository enhancement / version of global prefix-based +<tt>@git_base_url_list</tt> gitweb configuration variable (see +<a href="gitweb.conf.html">gitweb.conf(5)</a>).</p></div> +</dd> +<dt class="hdlist1"> +gitweb.owner +</dt> +<dd> +<p> + You can use the <tt>gitweb.owner</tt> repository configuration variable to set + repository’s owner. It is displayed in the project list and summary + page. +</p> +<div class="paragraph"><p>If it’s not set, filesystem directory’s owner is used (via GECOS field, +i.e. real name field from <strong>getpwuid</strong>(3)) if <tt>$projects_list</tt> is unset +(gitweb scans <tt>$projectroot</tt> for repositories); if <tt>$projects_list</tt> +points to file with list of repositories, then project owner defaults to +value from this file for given repository.</p></div> +</dd> +<dt class="hdlist1"> +various <tt>gitweb.*</tt> config variables (in config) +</dt> +<dd> +<p> + Read description of <tt>%feature</tt> hash for detailed list, and descriptions. + See also "Configuring gitweb features" section in <a href="gitweb.conf.html">gitweb.conf(5)</a> +</p> +</dd> +</dl></div> +</div> +<h2 id="_actions_and_urls">ACTIONS, AND URLS</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gitweb can use path_info (component) based URLs, or it can pass all necessary +information via query parameters. The typical gitweb URLs are broken down in to +five components:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>.../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments></tt></pre> +</div></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +repo +</dt> +<dd> +<p> + The repository the action will be performed on. +</p> +<div class="paragraph"><p>All actions except for those that list all available projects, +in whatever form, require this parameter.</p></div> +</dd> +<dt class="hdlist1"> +action +</dt> +<dd> +<p> + The action that will be run. Defaults to <em>projects_list</em> if repo + is not set, and to <em>summary</em> otherwise. +</p> +</dd> +<dt class="hdlist1"> +revision +</dt> +<dd> +<p> + Revision shown. Defaults to HEAD. +</p> +</dd> +<dt class="hdlist1"> +path +</dt> +<dd> +<p> + The path within the <repository> that the action is performed on, + for those actions that require it. +</p> +</dd> +<dt class="hdlist1"> +arguments +</dt> +<dd> +<p> + Any arguments that control the behaviour of the action. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Some actions require or allow to specify two revisions, and sometimes even two +pathnames. In most general form such path_info (component) based gitweb URL +looks like this:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>.../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments></tt></pre> +</div></div> +<div class="paragraph"><p>Each action is implemented as a subroutine, and must be present in %actions +hash. Some actions are disabled by default, and must be turned on via feature +mechanism. For example to enable <em>blame</em> view add the following to gitweb +configuration file:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>$feature{'blame'}{'default'} = [1];</tt></pre> +</div></div> +<h3 id="_actions">Actions:</h3><div style="clear:left"></div> +<div class="paragraph"><p>The standard actions are:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +project_list +</dt> +<dd> +<p> + Lists the available Git repositories. This is the default command if no + repository is specified in the URL. +</p> +</dd> +<dt class="hdlist1"> +summary +</dt> +<dd> +<p> + Displays summary about given repository. This is the default command if + no action is specified in URL, and only repository is specified. +</p> +</dd> +<dt class="hdlist1"> +heads +</dt> +<dt class="hdlist1"> +remotes +</dt> +<dd> +<p> + Lists all local or all remote-tracking branches in given repository. +</p> +<div class="paragraph"><p>The latter is not available by default, unless configured.</p></div> +</dd> +<dt class="hdlist1"> +tags +</dt> +<dd> +<p> + List all tags (lightweight and annotated) in given repository. +</p> +</dd> +<dt class="hdlist1"> +blob +</dt> +<dt class="hdlist1"> +tree +</dt> +<dd> +<p> + Shows the files and directories in a given repository path, at given + revision. This is default command if no action is specified in the URL, + and path is given. +</p> +</dd> +<dt class="hdlist1"> +blob_plain +</dt> +<dd> +<p> + Returns the raw data for the file in given repository, at given path and + revision. Links to this action are marked <em>raw</em>. +</p> +</dd> +<dt class="hdlist1"> +blobdiff +</dt> +<dd> +<p> + Shows the difference between two revisions of the same file. +</p> +</dd> +<dt class="hdlist1"> +blame +</dt> +<dt class="hdlist1"> +blame_incremental +</dt> +<dd> +<p> + Shows the blame (also called annotation) information for a file. On a + per line basis it shows the revision in which that line was last changed + and the user that committed the change. The incremental version (which + if configured is used automatically when JavaScript is enabled) uses + Ajax to incrementally add blame info to the contents of given file. +</p> +<div class="paragraph"><p>This action is disabled by default for performance reasons.</p></div> +</dd> +<dt class="hdlist1"> +commit +</dt> +<dt class="hdlist1"> +commitdiff +</dt> +<dd> +<p> + Shows information about a specific commit in a repository. The <em>commit</em> + view shows information about commit in more detail, the <em>commitdiff</em> + action shows changeset for given commit. +</p> +</dd> +<dt class="hdlist1"> +patch +</dt> +<dd> +<p> + Returns the commit in plain text mail format, suitable for applying with + <a href="git-am.html">git-am(1)</a>. +</p> +</dd> +<dt class="hdlist1"> +tag +</dt> +<dd> +<p> + Display specific annotated tag (tag object). +</p> +</dd> +<dt class="hdlist1"> +log +</dt> +<dt class="hdlist1"> +shortlog +</dt> +<dd> +<p> + Shows log information (commit message or just commit subject) for a + given branch (starting from given revision). +</p> +<div class="paragraph"><p>The <em>shortlog</em> view is more compact; it shows one commit per line.</p></div> +</dd> +<dt class="hdlist1"> +history +</dt> +<dd> +<p> + Shows history of the file or directory in a given repository path, + starting from given revision (defaults to HEAD, i.e. default branch). +</p> +<div class="paragraph"><p>This view is similar to <em>shortlog</em> view.</p></div> +</dd> +<dt class="hdlist1"> +rss +</dt> +<dt class="hdlist1"> +atom +</dt> +<dd> +<p> + Generates an RSS (or Atom) feed of changes to repository. +</p> +</dd> +</dl></div> +</div> +<h2 id="_webserver_configuration">WEBSERVER CONFIGURATION</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This section explains how to configure some common webservers to run gitweb. In +all cases, <tt>/path/to/gitweb</tt> in the examples is the directory you ran installed +gitweb in, and contains <tt>gitweb_config.perl</tt>.</p></div> +<div class="paragraph"><p>If you’ve configured a web server that isn’t listed here for gitweb, please send +in the instructions so they can be included in a future release.</p></div> +<h3 id="_apache_as_cgi">Apache as CGI</h3><div style="clear:left"></div> +<div class="paragraph"><p>Apache must be configured to support CGI scripts in the directory in +which gitweb is installed. Let’s assume that it is <em>/var/www/cgi-bin</em> +directory.</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>ScriptAlias /cgi-bin/ "/var/www/cgi-bin/" + +<Directory "/var/www/cgi-bin"> + Options Indexes FollowSymlinks ExecCGI + AllowOverride None + Order allow,deny + Allow from all +</Directory></tt></pre> +</div></div> +<div class="paragraph"><p>With that configuration the full path to browse repositories would be:</p></div> +<div class="literalblock"> +<div class="content"> +<pre><tt>http://server/cgi-bin/gitweb.cgi</tt></pre> +</div></div> +<h3 id="_apache_with_mod_perl_via_modperl_registry">Apache with mod_perl, via ModPerl::Registry</h3><div style="clear:left"></div> +<div class="paragraph"><p>You can use mod_perl with gitweb. You must install Apache::Registry +(for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable +this support.</p></div> +<div class="paragraph"><p>Assuming that gitweb is installed to <em>/var/www/perl</em>, the following +Apache configuration (for mod_perl 2.x) is suitable.</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>Alias /perl "/var/www/perl" + +<Directory "/var/www/perl"> + SetHandler perl-script + PerlResponseHandler ModPerl::Registry + PerlOptions +ParseHeaders + Options Indexes FollowSymlinks +ExecCGI + AllowOverride None + Order allow,deny + Allow from all +</Directory></tt></pre> +</div></div> +<div class="paragraph"><p>With that configuration the full path to browse repositories would be:</p></div> +<div class="literalblock"> +<div class="content"> +<pre><tt>http://server/perl/gitweb.cgi</tt></pre> +</div></div> +<h3 id="_apache_with_fastcgi">Apache with FastCGI</h3><div style="clear:left"></div> +<div class="paragraph"><p>Gitweb works with Apache and FastCGI. First you need to rename, copy +or symlink gitweb.cgi to gitweb.fcgi. Let’s assume that gitweb is +installed in <em>/usr/share/gitweb</em> directory. The following Apache +configuration is suitable (UNTESTED!)</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>FastCgiServer /usr/share/gitweb/gitweb.cgi +ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi + +Alias /gitweb/static /usr/share/gitweb/static +<Directory /usr/share/gitweb/static> + SetHandler default-handler +</Directory></tt></pre> +</div></div> +<div class="paragraph"><p>With that configuration the full path to browse repositories would be:</p></div> +<div class="literalblock"> +<div class="content"> +<pre><tt>http://server/gitweb</tt></pre> +</div></div> +</div> +<h2 id="_advanced_web_server_setup">ADVANCED WEB SERVER SETUP</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All of those examples use request rewriting, and need <tt>mod_rewrite</tt> +(or equivalent; examples below are written for Apache).</p></div> +<h3 id="_single_url_for_gitweb_and_for_fetching">Single URL for gitweb and for fetching</h3><div style="clear:left"></div> +<div class="paragraph"><p>If you want to have one URL for both gitweb and your <tt>http://</tt> +repositories, you can configure Apache like this:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt><VirtualHost *:80> + ServerName git.example.org + DocumentRoot /pub/git + SetEnv GITWEB_CONFIG /etc/gitweb.conf + + # turning on mod rewrite + RewriteEngine on + + # make the front page an internal rewrite to the gitweb script + RewriteRule ^/$ /cgi-bin/gitweb.cgi + + # make access for "dumb clients" work + RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ + /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] +</VirtualHost></tt></pre> +</div></div> +<div class="paragraph"><p>The above configuration expects your public repositories to live under +<em>/pub/git</em> and will serve them as <tt>http://git.domain.org/dir-under-pub-git</tt>, +both as cloneable GIT URL and as browseable gitweb interface. If you then +start your <a href="git-daemon.html">git-daemon(1)</a> with <tt>--base-path=/pub/git --export-all</tt> +then you can even use the <tt>git://</tt> URL with exactly the same path.</p></div> +<div class="paragraph"><p>Setting the environment variable <tt>GITWEB_CONFIG</tt> will tell gitweb to use the +named file (i.e. in this example <em>/etc/gitweb.conf</em>) as a configuration for +gitweb. You don’t really need it in above example; it is required only if +your configuration file is in different place than built-in (during +compiling gitweb) <em>gitweb_config.perl</em> or <em>/etc/gitweb.conf</em>. See +<a href="gitweb.conf.html">gitweb.conf(5)</a> for details, especially information about precedence +rules.</p></div> +<div class="paragraph"><p>If you use the rewrite rules from the example you <strong>might</strong> also need +something like the following in your gitweb configuration file +(<em>/etc/gitweb.conf</em> following example):</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>@stylesheets = ("/some/absolute/path/gitweb.css"); +$my_uri = "/"; +$home_link = "/"; +$per_request_config = 1;</tt></pre> +</div></div> +<div class="paragraph"><p>Nowadays though gitweb should create HTML base tag when needed (to set base +URI for relative links), so it should work automatically.</p></div> +<h3 id="_webserver_configuration_with_multiple_projects_root">Webserver configuration with multiple projects' root</h3><div style="clear:left"></div> +<div class="paragraph"><p>If you want to use gitweb with several project roots you can edit your +Apache virtual host and gitweb configuration files in the following way.</p></div> +<div class="paragraph"><p>The virtual host configuration (in Apache configuration file) should look +like this:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt><VirtualHost *:80> + ServerName git.example.org + DocumentRoot /pub/git + SetEnv GITWEB_CONFIG /etc/gitweb.conf + + # turning on mod rewrite + RewriteEngine on + + # make the front page an internal rewrite to the gitweb script + RewriteRule ^/$ /cgi-bin/gitweb.cgi [QSA,L,PT] + + # look for a public_git folder in unix users' home + # http://git.example.org/~<user>/ + RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] + + # http://git.example.org/+<user>/ + #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] + + # http://git.example.org/user/<user>/ + #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] + + # defined list of project roots + RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT] + RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT] + + # make access for "dumb clients" work + RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ + /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] +</VirtualHost></tt></pre> +</div></div> +<div class="paragraph"><p>Here actual project root is passed to gitweb via <tt>GITWEB_PROJECT_ROOT</tt> +environment variable from a web server, so you need to put the following +line in gitweb configuration file (<em>/etc/gitweb.conf</em> in above example):</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";</tt></pre> +</div></div> +<div class="paragraph"><p><strong>Note</strong> that this requires to be set for each request, so either +<tt>$per_request_config</tt> must be false, or the above must be put in code +referenced by <tt>$per_request_config</tt>;</p></div> +<div class="paragraph"><p>These configurations enable two things. First, each unix user (<tt><user></tt>) of +the server will be able to browse through gitweb git repositories found in +<em>~/public_git/</em> with the following url:</p></div> +<div class="literalblock"> +<div class="content"> +<pre><tt>http://git.example.org/~<user>/</tt></pre> +</div></div> +<div class="paragraph"><p>If you do not want this feature on your server just remove the second +rewrite rule.</p></div> +<div class="paragraph"><p>If you already use ‘mod_userdir` in your virtual host or you don’t want to +use the '~’ as first character, just comment or remove the second rewrite +rule, and uncomment one of the following according to what you want.</p></div> +<div class="paragraph"><p>Second, repositories found in <em>/pub/scm/</em> and <em>/var/git/</em> will be accessible +through <tt>http://git.example.org/scm/</tt> and <tt>http://git.example.org/var/</tt>. +You can add as many project roots as you want by adding rewrite rules like +the third and the fourth.</p></div> +<h3 id="_path_info_usage">PATH_INFO usage</h3><div style="clear:left"></div> +<div class="paragraph"><p>If you enable PATH_INFO usage in gitweb by putting</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>$feature{'pathinfo'}{'default'} = [1];</tt></pre> +</div></div> +<div class="paragraph"><p>in your gitweb configuration file, it is possible to set up your server so +that it consumes and produces URLs in the form</p></div> +<div class="literalblock"> +<div class="content"> +<pre><tt>http://git.example.com/project.git/shortlog/sometag</tt></pre> +</div></div> +<div class="paragraph"><p>i.e. without <em>gitweb.cgi</em> part, by using a configuration such as the +following. This configuration assumes that <em>/var/www/gitweb</em> is the +DocumentRoot of your webserver, contains the gitweb.cgi script and +complementary static files (stylesheet, favicon, JavaScript):</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt><VirtualHost *:80> + ServerAlias git.example.com + + DocumentRoot /var/www/gitweb + + <Directory /var/www/gitweb> + Options ExecCGI + AddHandler cgi-script cgi + + DirectoryIndex gitweb.cgi + + RewriteEngine On + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule ^.* /gitweb.cgi/$0 [L,PT] + </Directory> +</VirtualHost></tt></pre> +</div></div> +<div class="paragraph"><p>The rewrite rule guarantees that existing static files will be properly +served, whereas any other URL will be passed to gitweb as PATH_INFO +parameter.</p></div> +<div class="paragraph"><p><strong>Notice</strong> that in this case you don’t need special settings for +<tt>@stylesheets</tt>, <tt>$my_uri</tt> and <tt>$home_link</tt>, but you lose "dumb client" +access to your project .git dirs (described in "Single URL for gitweb and +for fetching" section). A possible workaround for the latter is the +following: in your project root dir (e.g. <em>/pub/git</em>) have the projects +named <strong>without</strong> a .git extension (e.g. <em>/pub/git/project</em> instead of +<em>/pub/git/project.git</em>) and configure Apache as follows:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt><VirtualHost *:80> + ServerAlias git.example.com + + DocumentRoot /var/www/gitweb + + AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3 + <Directory /var/www/gitweb> + Options ExecCGI + AddHandler cgi-script cgi + + DirectoryIndex gitweb.cgi + + RewriteEngine On + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule ^.* /gitweb.cgi/$0 [L,PT] + </Directory> +</VirtualHost></tt></pre> +</div></div> +<div class="paragraph"><p>The additional AliasMatch makes it so that</p></div> +<div class="literalblock"> +<div class="content"> +<pre><tt>http://git.example.com/project.git</tt></pre> +</div></div> +<div class="paragraph"><p>will give raw access to the project’s git dir (so that the project can be +cloned), while</p></div> +<div class="literalblock"> +<div class="content"> +<pre><tt>http://git.example.com/project</tt></pre> +</div></div> +<div class="paragraph"><p>will provide human-friendly gitweb access.</p></div> +<div class="paragraph"><p>This solution is not 100% bulletproof, in the sense that if some project has +a named ref (branch, tag) starting with <em>git/</em>, then paths such as</p></div> +<div class="literalblock"> +<div class="content"> +<pre><tt>http://git.example.com/project/command/abranch..git/abranch</tt></pre> +</div></div> +<div class="paragraph"><p>will fail with a 404 error.</p></div> +</div> +<h2 id="_bugs">BUGS</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Please report any bugs or feature requests to <a href="mailto:git@vger.kernel.org">git@vger.kernel.org</a>, +putting "gitweb" in the subject of email.</p></div> +</div> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="gitweb.conf.html">gitweb.conf(5)</a>, <a href="git-instaweb.html">git-instaweb(1)</a></p></div> +<div class="paragraph"><p><em>gitweb/README</em>, <em>gitweb/INSTALL</em></p></div> +</div> +<h2 id="_git">GIT</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div> +</div> +</div> +<div id="footnotes"><hr /></div> +<div id="footer"> +<div id="footer-text"> +Last updated 2011-10-19 11:41:17 PDT +</div> +</div> +</body> +</html> 